home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / man / lib.fmt / c / Disk.man < prev    next >
Encoding:
Text File  |  1990-10-31  |  17.6 KB  |  399 lines
  1.  
  2.  
  3.  
  4. Disk                  C Library Procedures                   Disk
  5.  
  6.  
  7.  
  8. _________________________________________________________________
  9.  
  10. NNAAMMEE
  11.      Disk_ReadLabel,      Disk_WriteLabel,       Disk_EraseLabel,  |
  12.      Disk_NewLabel,Disk_ReadDecLabel,         Disk_WriteDecLabel,  |
  13.      Disk_ReadSunLabel,                       Disk_WriteSunLabel,  |
  14.      Disk_ReadDomainHeader,               Disk_WriteDomainHeader,  |
  15.      Disk_ReadSummaryInfo,                 Disk_WriteSummaryInfo,  |
  16.      Disk_SectorRead,      Disk_SectorWrite,      Disk_BlockRead,  |
  17.      Disk_BlockWrite,      Disk_BadBlockRead,      Disk_FragRead,  |
  18.      Disk_FragWrite,                      Disk_PrintDomainHeader,  |
  19.      Disk_PrintSummaryInfo,             Disk_PrintFileDescBitmap,  |
  20.      Disk_PrintDataBlockBitmap,               Disk_PrintDirEntry,  |
  21.      Disk_PrintLabel - Package for accessing OFS file systems via  |
  22.      raw disks
  23.  
  24. SSYYNNOOPPSSIISS
  25.      #include <disk.h>                                             |
  26.  
  27.      Disk_Label *                                                  |
  28.      DDiisskk__RReeaaddLLaabbeell(_f_i_l_e_I_D)                                        |
  29.      int                                                           |
  30.      DDiisskk__WWrriitteeLLaabbeell(_f_i_l_e_I_D, _l_a_b_e_l_P_t_r)                             |
  31.      Disk_Label *                                                  |
  32.      DDiisskk__NNeewwLLaabbeell(_l_a_b_e_l_T_y_p_e)                                      |
  33.      int                                                           |
  34.      DDiisskk__EErraasseeLLaabbeell(_f_i_l_e_I_D, _l_a_b_e_l_T_y_p_e)                            |
  35.      Dec_DiskLabel *                                               |
  36.      DDiisskk__RReeaaddDDeeccLLaabbeell(_f_i_l_e_I_D)                                     |
  37.      int                                                           |
  38.      DDiisskk__WWrriitteeDDeeccLLaabbeell(_f_i_l_e_I_D, _d_e_c_L_a_b_e_l_P_t_r)                       |
  39.      Sun_DiskLabel *
  40.      DDiisskk__RReeaaddSSuunnLLaabbeell(_f_i_l_e_I_D)
  41.      int                                                           |
  42.      DDiisskk__WWrriitteeSSuunnLLaabbeell(_f_i_l_e_I_D, _s_u_n_L_a_b_e_l_P_t_r)                       |
  43.      Ofs_DomainHeader *                                            |
  44.      DDiisskk__RReeaaddDDoommaaiinnHHeeaaddeerr(_f_i_l_e_I_D, _l_a_b_e_l_P_t_r)                       |
  45.      int                                                           |
  46.      DDiisskk__WWrriitteeDDoommaaiinnHHeeaaddeerr(_f_i_l_e_I_D, _l_a_b_e_l_P_t_r, _h_e_a_d_e_r_P_t_r)           |
  47.      Ofs_SummaryInfo *                                             |
  48.      DDiisskk__RReeaaddSSuummmmaarryyIInnffoo(_f_i_l_e_I_D, _l_a_b_e_l_P_t_r)                        |
  49.      int                                                           |
  50.      DDiisskk__WWrriitteeSSuummmmaarryyIInnffoo(_f_i_l_e_I_D, _l_a_b_e_l_P_t_r, _s_u_m_m_a_r_y_P_t_r)           |
  51.      int
  52.      DDiisskk__SSeeccttoorrRReeaadd(_f_i_l_e_I_D, _i_n_d_e_x, _c_o_u_n_t, _b_u_f_f_e_r)
  53.      int
  54.      DDiisskk__SSeeccttoorrWWrriittee(_f_i_l_e_I_D, _i_n_d_e_x, _c_o_u_n_t, _b_u_f_f_e_r)
  55.      int
  56.      DDiisskk__BBlloocckkRReeaadd(_f_i_l_e_I_D, _h_e_a_d_e_r_P_t_r, _i_n_d_e_x, _c_o_u_n_t, _b_u_f_f_e_r)
  57.      int
  58.      DDiisskk__BBlloocckkWWrriittee(_f_i_l_e_I_D, _h_e_a_d_e_r_P_t_r, _i_n_d_e_x, _c_o_u_n_t, _b_u_f_f_e_r)
  59.      int
  60.  
  61.  
  62.  
  63. Sprite v.1.0       Printed:  October 31, 1990                   1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Disk                  C Library Procedures                   Disk
  71.  
  72.  
  73.  
  74.      DDiisskk__BBaaddBBlloocckkRReeaadd(_f_i_l_e_I_D, _h_e_a_d_e_r_P_t_r, _i_n_d_e_x, _b_u_f_f_e_r)
  75.      int
  76.      DDiisskk__FFrraaggRReeaadd(_f_i_l_e_I_D, _h_e_a_d_e_r_P_t_r, _i_n_d_e_x, _c_o_u_n_t, _b_u_f_f_e_r)
  77.      int
  78.      DDiisskk__FFrraaggWWrriittee(_f_i_l_e_I_D, _h_e_a_d_e_r_P_t_r, _i_n_d_e_x, _c_o_u_n_t, _b_u_f_f_e_r)
  79.      void
  80.      DDiisskk__PPrriinnttDDoommaaiinnHHeeaaddeerr(_h_e_a_d_e_r_P_t_r)
  81.      void
  82.      DDiisskk__PPrriinnttSSuummmmaarryyIInnffoo(_s_u_m_m_a_r_y_P_t_r)
  83.      DDiisskk__PPrriinnttLLaabbeell(_l_a_b_e_l_P_t_r)                                     |
  84.      void
  85.      DDiisskk__PPrriinnttFFiilleeDDeessccBBiittmmaapp(_h_e_a_d_e_r_P_t_r, _b_i_t_m_a_p)
  86.      void
  87.      DDiisskk__PPrriinnttDDaattaaBBlloocckkBBiittmmaapp(_h_e_a_d_e_r_P_t_r, _b_i_t_m_a_p)
  88.      void
  89.      DDiisskk__PPrriinnttDDiirrEEnnttrryy(_d_i_r_E_n_t_r_y_P_t_r)
  90.  
  91.  
  92. AARRGGUUMMEENNTTSS
  93.      int                _f_i_l_e_I_D        (in)      File   descriptor
  94.                                                 from  ooppeenn of raw
  95.                                                 disk.
  96.  
  97.      int                _p_a_r_t_i_t_i_o_n     (in)      Index  of  parti-
  98.                                                 tion  to  access,
  99.                                                 0-7.               |
  100.  
  101.      Disk_Label         *_l_a_b_e_l_P_t_r     (in)                              ||
  102.                                                 Basic disk infor-  |
  103.                                                 mation       from  |
  104.                                                 DDiisskk__RReeaaddLLaabbeell.    |
  105.  
  106.      Disk_NativeLabelType             _l_a_b_e_l_T_y_p_e(in)                     ||
  107.                                                 Type  of machine-  |
  108.                                                 specific (native)  |
  109.                                                 disk label on the  |
  110.                                                 disk.              |
  111.  
  112.      Dec_DiskLabel  *_d_e_c_L_a_b_e_l_P_t_r                                        ||
  113.                                                 Native disk label  |
  114.                                                 for ds3100s.       |
  115.  
  116.      Sun_DiskLabel  *_s_u_n_L_a_b_e_l_P_t_r                                        ||
  117.                                                 Native disk label  |
  118.                                                 for Suns.
  119.  
  120.      int                _i_n_d_e_x         (in)      Index  of   first
  121.                                                 (sector/block/fragment)
  122.                                                 to transfer.
  123.  
  124.      int                _c_o_u_n_t         (in)      Number         of
  125.                                                 (sectors/blocks/fragments)
  126.  
  127.  
  128.  
  129. Sprite v.1.0       Printed:  October 31, 1990                   2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Disk                  C Library Procedures                   Disk
  137.  
  138.  
  139.  
  140.                                                 to transfer.
  141.  
  142.      char               *_b_u_f_f_e_r       (in)      Buffer  for  data
  143.                                                 transferred.
  144.  
  145.      Ofs_DomainHeader   *_h_e_a_d_e_r_P_t_r    (in)      Disk       header
  146.                                                 information  from
  147.                                                 DDiisskk__RReeaaddDDiisskkHHeeaaddeerr.
  148.  
  149.      Ofs_SummaryInfo    *_s_u_m_m_a_r_y_P_t_r   (in)      Disk      summary
  150.                                                 information  sec-
  151.                                                 tor.
  152.  
  153.      char               *_b_i_t_m_a_p       (in)      Array  of  bitmap
  154.                                                 bytes.
  155.  
  156.      Fslcl_DirEntry     *_d_i_r_E_n_t_r_y_P_t_r  (in)      Directory   entry
  157.                                                 structure.
  158.  
  159. _________________________________________________________________
  160.  
  161.  
  162. IINNTTRROODDUUCCTTIIOONN
  163.      The DDiisskk package is used to read and write  raw  disks  that
  164.      are  formatted to contain Sprite file systems.  To use these
  165.      routines correctly it is important to understand disk _p_a_r_t_i_-
  166.      _t_i_o_n_s,  file  system _h_e_a_d_e_r _i_n_f_o_r_m_a_t_i_o_n, file system _b_l_o_c_k_s,
  167.      and file system block _f_r_a_g_m_e_n_t_s.
  168.  
  169.      Each physical disk is divided into as many as 8  partitions.
  170.      The  letters  'a'  through 'h' are used to distinguish these
  171.      different partitions in the  names  of  the  special  device
  172.      files  that  are  used  to access them.  Thus ``/dev/rsd0a''
  173.      references the first (zero'th) partition on disk  rrssdd00.  The  |
  174.      partitioning information is stored on the disk in the ``disk  |
  175.      label''.  This label is in a machine-dependent  format,  and  |
  176.      is  referred  to  as the ``native disk label''.  Native disk  |
  177.      labels are kept in a machine-dependent location on the disk.  |
  178.      This  is  usually  in sector 0 or some other sector near the  |
  179.      start of the  first  partition.   The  ffssmmaakkee  program  also  |
  180.      copies  the  label  to a partition when it formats it into a  |
  181.      file   system.   The    routines    DDiisskk__RReeaaddSSuunnLLaabbeell    and  |
  182.      DDiisskk__RReeaaddDDeeccLLaabbeell  can  be  used  to  read  the  native disk  |
  183.      labels.                                                       |
  184.  
  185.      It is not always convenient to deal with native disk labels.  |
  186.      For this reason a generic label type and associated routines  |
  187.      have been provided.  The type DDiisskk__LLaabbeell is a standard  for-  |
  188.      mat  for disk labels.  The routine DDiisskk__RReeaaddLLaabbeell is used to  |
  189.      read a native disk label off the disk and convert it into  a  |
  190.      DDiisskk__LLaabbeell.   The  routine  DDiisskk__WWrriitteeLLaabbeell  will  convert a  |
  191.      DDiisskk__LLaabbeell into a native disk label  and  write  it  on  the  |
  192.      disk.   Two  more  procedures  are provided for manipulating  |
  193.      disk labels.  DDiisskk__EErraasseeLLaabbeell will erase a native disk label  |
  194.  
  195.  
  196.  
  197. Sprite v.1.0       Printed:  October 31, 1990                   3
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204. Disk                  C Library Procedures                   Disk
  205.  
  206.  
  207.  
  208.      from  the  disk,  and  DDiisskk__NNeewwLLaabbeell is used to create a new  |
  209.      label if the disk does not have one already.   The  contents  |
  210.      of a DDiisskk__LLaabbeell are defined in <disk.h>.
  211.  
  212.      The detailed structure of the file system is  defined  by  a
  213.      Ofs_DomainHeader  structure that located on the disk accord-
  214.      ing to the  DDiisskk__LLaabbeell.   This  can  be  obtained  with  the
  215.      DDiisskk__RReeaaddDDoommaaiinnHHeeaaddeerr   procedure.    The   Ofs_DomainHeader
  216.      structure is defined in <kernel/fsdm.h>, and  is  passed  to
  217.      the  block  and  fragment I/O routines so they can correctly
  218.      locate blocks and fragments.
  219.  
  220.      A secondary data structure called the summary information is  |
  221.      kept  on  disk  following  the  domain  header.  The summary  |
  222.      information consists of a single sector  and  contains  such  |
  223.      information  as  the number of free blocks and file descrip-  |
  224.      tors.   The  Ofs_SummaryInfo   structure   is   defined   in  |
  225.      <kernel/fsdm.h>.   The  location  of  the  summary sector is  |
  226.      stored in the DDiisskk__LLaabbeell.  The summary sector  can  be  read  |
  227.      and    written    using    the    DDiisskk__RReeaaddSSuummmmaarryyIInnffoo   and  |
  228.      DDiisskk__WWrriitteeSSuummmmaarryyIInnffoo procedures.
  229.  
  230. SSEECCTTOORR II//OO
  231.      DDiisskk__SSeeccttoorrRReeaadd and DDiisskk__SSeeccttoorrWWrriittee read and write  sectors
  232.      from  the disk without regard to the underlying block struc-
  233.      ture.  Their  _i_n_d_e_x  argument  specifies  the  first  sector
  234.      (starting  from  zero) to transfer, relative to the start of
  235.      the partition.  The sector offsets given in  the  DDiisskk__LLaabbeell
  236.      structure are useful with this routine.
  237.  
  238. BBLLOOCCKK II//OO
  239.      The file system is arranged in  block-sized  chunks  on  the
  240.      disk.    FFSS__BBLLOOCCKK__SSIIZZEE   defines  how  many  bytes  this  is
  241.      (currently 4 Kbytes).  Due to disk  geometry  considerations
  242.      consecutive  blocks  may  or  may not be contiguous on disk.
  243.      DDiisskk__BBlloocckkRReeaadd and DDiisskk__BBlloocckkWWrriittee use  geometry  and  block
  244.      layout  information  in  the  Ofs_DomainHeader  to correctly
  245.      locate disk blocks.  The _i_n_d_e_x argument to these routines is
  246.      a  block index, counting from the beginning of the partition
  247.      (see the warning below!).
  248.  
  249.      DDiisskk__BBaaddBBlloocckkRReeaadd is used to re-read a bad file system block
  250.      and  determine  which sectors are bad.  It returns a bitmask
  251.      with bits set to indicate which of the sectors were success-
  252.      fully  read.   Bit  _i in the mask corresponds to sector _i in
  253.      the block.  DDIISSKK__SSEECCTTOORRSS__PPEERR__BBLLOOCCKK defines how  many  sector
  254.      there are in each file system block.
  255.  
  256. FFRRAAGGMMEENNTT II//OO
  257.      Each file system block  is  sub-divided  into  fragments  to
  258.      optimize  allocation of small files.  Currently the fragment
  259.      size is 1 Kbyte, so there are 4  fragments  to  each  block.
  260.  
  261.  
  262.  
  263. Sprite v.1.0       Printed:  October 31, 1990                   4
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270. Disk                  C Library Procedures                   Disk
  271.  
  272.  
  273.  
  274.      DDiisskk__FFrraaggRReeaadd  and DDiisskk__FFrraaggWWrriittee are used to read and write
  275.      fragments.  The _i_n_d_e_x argument to these routines is a  frag-
  276.      ment  index,  counting  from  the beginning of the partition
  277.      (see the warning below!).  The _c_o_u_n_t argument to these  rou-
  278.      tines should not be greater than the number of fragments per
  279.      file system block.
  280.  
  281. BBLLOOCCKK AANNDD FFRRAAGGMMEENNTT IINNDDEEXXEESS
  282.      WWAARRNNIINNGG:: there are several caveats about block  numbers  and
  283.      fragment  numbers as used by the Sprite file system.  A par-
  284.      tition is divided into areas for bitmaps, file  descriptors,
  285.      and  data  blocks.   These  divisions  are  specified in the
  286.      Ofs_DomainHeader structure in terms  of  block  offsets  and
  287.      number  of  blocks.   However, _b_l_o_c_k _n_u_m_b_e_r_s _a_r_e _n_o_t _k_e_p_t _i_n
  288.      _d_i_s_k _m_a_p_s,  _o_n_l_y  _f_r_a_g_m_e_n_t  _n_u_m_b_e_r_s.   When  traversing  the
  289.      direct and indirect blocks that define where a file's blocks
  290.      are, fragment indexes must be  converted  to  block  indexes
  291.      before   using  either  DDiisskk__BBlloocckkRReeaadd  or  DDiisskk__BBlloocckkWWrriittee.
  292.      Also, _d_i_r_e_c_t _b_l_o_c_k _p_o_i_n_t_e_r_s _i_n _t_h_e _m_a_p_s _a_r_e _f_r_a_g_m_e_n_t _i_n_d_e_x_e_s
  293.      _r_e_l_a_t_i_v_e  _t_o  _t_h_e  _s_t_a_r_t  _o_f _t_h_e _d_a_t_a _b_l_o_c_k _a_r_e_a _o_f _t_h_e _f_i_l_e
  294.      _s_y_s_t_e_m.  Thus to convert from a direct block  pointer  to  a
  295.      physical fragment index:
  296.  
  297.           fragIndex = blockPointer + (headerPtr->dataOffset * FS_FRAGMENTS_PER_BLOCK);
  298.           blockIndex = fragIndex / FS_FRAGMENTS_PER_BLOCK;
  299.  
  300.      The last main caveat is that  _i_n_d_i_r_e_c_t  _b_l_o_c_k  _p_o_i_n_t_e_r_s  _a_r_e
  301.      _p_h_y_s_i_c_a_l _f_r_a_g_m_e_n_t _i_n_d_e_x_e_s.  They do not need to be offset in
  302.      the same way as direct block pointers.  This applies to  any
  303.      block  pointer  that points to an indirect block, never to a
  304.      block pointer that points to a data block.
  305.  
  306. PPRRIINNTTIINNGG UUTTIILLIITTIIEESS
  307.      The last set of procedures in this package are used to print
  308.      out  contents  of  the  file system.  DDiisskk__PPrriinnttDDoommaaiinnHHeeaaddeerr
  309.      prints    out     the     domain     header     information.
  310.      DDiisskk__PPrriinnttSSuummmmaarryyIInnffoo  prints  out  the summary disk sector.
  311.      This sector is used to keep the prefix under which the  disk
  312.      is  exported,  the  current  number  of blocks allocated and
  313.      free, and whether or not the disk was safely sync'ed at last
  314.      reboot.              DDiisskk__PPrriinnttFFiilleeDDeessccBBiittmmaapp            and
  315.      DDiisskk__PPrriinnttDDaattaaBBlloocckkBBiittmmaapp print out the file descriptor  and
  316.      data  block  bitmaps  in  hex.  A zero bit represents a free
  317.      descriptor or block.  DDiisskk__PPrriinnttDDiirrEEnnttrryy prints out a direc-
  318.      tory entry.
  319.  
  320. SSEEEE AALLSSOO
  321.      fscheck, fsmake, labeldisk, installboot
  322.  
  323. KKEEYYWWOORRDDSS
  324.      disk, block, sector, fragment
  325.  
  326.  
  327.  
  328.  
  329. Sprite v.1.0       Printed:  October 31, 1990                   5
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336. Disk                  C Library Procedures                   Disk
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392. Sprite v.1.0       Printed:  October 31, 1990                   6
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.